<!DOCTYPE HTML><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

<META charset="utf-8">

<LINK REL="STYLESHEET" HREF="../book.css" TYPE="text/css">
<TITLE>
Registering editor actions
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY>
<H2>Registering editor actions</H2>
<p>The text editor framework provides many utility classes that aid in presenting
and updating text and source code.&nbsp; Now we will turn our attention to the workbench in
which the editor is but one part.&nbsp; How does the editor interact with other
workbench features such as context menus, menu bars, and tool bars?</p>

<h3>Editor Menu Bar Actions</h3>

<p>To understand how editors register themselves with the workbench and provide
actions for the workbench menu bar, see the section discussing <a href="workbench_basicext_editors.htm">org.eclipse.ui.editors</a>.&nbsp;
We won't rehash that information here.&nbsp;&nbsp;We'll just take a quick look
at the markup where the Java example editor registers its editor.</p>

<pre>&lt;extension
      point=&quot;org.eclipse.ui.editors&quot;&gt;
   &lt;editor
         name=&quot;%javaEditorName&quot;
         icon=&quot;icons/obj16/java.png&quot;
         extensions=&quot;jav&quot;
         <b>contributorClass=&quot;org.eclipse.ui.examples.javaeditor.JavaActionContributor&quot;</b>
         class=&quot;org.eclipse.ui.examples.javaeditor.JavaEditor&quot;
         id=&quot;org.eclipse.ui.JavaEditor&quot;&gt;
   &lt;/editor&gt;
&lt;/extension&gt;</pre>

<p>Workbench menu bar actions are contributed by the <b>JavaActionContributor</b>.&nbsp; 
  It implements actions that are placed in the workbench <b>Edit</b> menu and 
  the workbench tool bar.</p>

<pre>public JavaActionContributor() {
	super();
	fContentAssistProposal= <b>new RetargetTextEditorAction</b>(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistProposal.&quot;); //$NON-NLS-1$
	...
	fContentAssistTip= new RetargetTextEditorAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistTip.&quot;); //$NON-NLS-1$
	...
	fTogglePresentation= new PresentationAction();
}</pre>
<p>The first two actions are defined as retargetable text editor actions. The 
  principle is similar to the retargetable actions
  provided by the workbench. Retargetable text editor actions represent menu entries 
  which the action contributor dynamically binds to corresponding actions provided 
  by the active editor. When the active editor changes, the action to which a 
  retargetable text editor action is bound changes as well. The following snippet 
  shows that the editor action contributor finds the corresponding action by asking 
  the editor for an action of a given id:</p>
<pre>protected final IAction getAction(ITextEditor editor, String actionId) {<br>	return (editor == null ? null : editor.getAction(actionId));<br>}

public void setActiveEditor(IEditorPart part) {<br>	super.setActiveEditor(part);<br>	ITextEditor editor= null;<br>	if (part instanceof ITextEditor)<br>		editor= (ITextEditor) part;<br>	fContentAssistProposal.setAction(getAction(editor, &quot;ContentAssistProposal&quot;));<br>	fContentAssistTip.setAction(getAction(editor, &quot;ContentAssistTip&quot;));<br>	fTogglePresentation.setEditor(editor);<br>	fTogglePresentation.update();<br>}</pre>
<p>The id must be the same under which the action is registered with the editor 
  as given here for the <b>JavaTextEditor</b>. (See also next section.):<br>
</p>
<pre>protected void createActions() {
	super.createActions();
		
	IAction a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistProposal.&quot;, this, ISourceViewer.CONTENTASSIST_PROPOSALS); //$NON-NLS-1$
	<b>a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);</b>
	setAction(&quot;ContentAssistProposal&quot;, a); 
		
	a= new TextOperationAction(JavaEditorMessages.getResourceBundle(), &quot;ContentAssistTip.&quot;, this, ISourceViewer.CONTENTASSIST_CONTEXT_INFORMATION);  //$NON-NLS-1$
	a.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_CONTEXT_INFORMATION);
	setAction(&quot;ContentAssistTip&quot;, a); 
}</pre>

<p>The third action in the contributor is a concrete action added to the workbench 
  tool bar.&nbsp; It toggles the state of the editor between showing the highlighted 
  range (as dictated by the Java example's content outliner) and showing the entire 
  file.&nbsp; This action only appears in the tool bar.</p>

<h3>Editor Context Menus</h3>

The editor context menus are created and managed in the <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
 and <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a> framework.
<p>The method <b>createActions</b> is used to register actions with the editor.&nbsp; 
  This includes actions appropriate for the editor context menus or any actions 
  contributed in extension definitions.&nbsp; In the Java example editor, only 
  the actions that get bound to the retargetable actions are created.&nbsp; However, 
  the Java example editor also inherits the actions created by <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a> 
  and its superclasses.&nbsp; These actions can be used in the editor context 
  menus.</p>
<p>The <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a>
method <b>editorContextMenuAboutToShow</b> is used in the framework to allow
editors to add actions to the context menu for the editing area.&nbsp; You can
use a menu path to decide exactly where your action should appear.&nbsp; Valid
menu paths inside the editor context menu are defined in the implementation of
this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
<p>There are several ways to add an action to this menu.&nbsp; The first way is 
  by adding an action using only the id under which it is registered with the 
  editor.&nbsp; For example, the <b>JavaTextEditor</b> adds its actions for content 
  assistance to the menu when this method is called.&nbsp; Actions will not appear 
  in the menu when no action is registered under the used id.</p>
<pre>public void editorContextMenuAboutToShow(MenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, &quot;ContentAssistProposal&quot;); 
	addAction(menu, &quot;ContentAssistTip&quot;); 
}</pre>
<p>The superclass <a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"><b>TextEditor</b></a> 
  adds actions a second way - by specifying a menu group in the context menu 
  for placing the action.&nbsp; In this case the actions (<b>Shift Left</b>, <b>Shift 
  Right</b>) do appear in the context menu in the group defined by <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>.</p>
<pre>protected void editorContextMenuAboutToShow(IMenuManager menu) {
	super.editorContextMenuAboutToShow(menu);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_RIGHT);
	addAction(menu, ITextEditorActionConstants.GROUP_EDIT, ITextEditorActionConstants.SHIFT_LEFT);
}</pre>
<p><img src="images/javaeditorcontextmenu.png" alt="Editor context menu" style="border:0"> </p>
<p>The method <b>rulerContextMenuAboutToShow</b>  is used in the same way before
the ruler's context menu is shown.&nbsp; The implementation of this method in <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a>
defines the groups in which items can be added to the menu. </p>
<h3>Menu Ids </h3>
<p>The editor context and ruler context menus can be assigned ids so that other
plug-ins can contribute to these menus in their extensions.&nbsp; The scheme for
establishing menu ids is more flexible since the original version of the
platform.&nbsp; However, the framework can run in a compatibility mode in order
to remain compatible with plug-ins developed for the original version.&nbsp; You
can use <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setCompatibilityMode()"><b>AbstractTextEditor.setCompatibilityMode()</b></a>
to control this behavior.&nbsp; The default setting is true. </p>

<h4>1.0 Compatible Menu Ids </h4>
<p>When the compatibility mode is true, the ids of the editor and ruler context 
  menus can be set using <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html"><b>AbstractTextEditor</b></a> 
  protocol.&nbsp; The methods <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setEditorContextMenuId(java.lang.String)"><b>setEditorContextMenuId</b></a> 
  and <a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html#setRulerContextMenuId(java.lang.String)"><b>setRulerContextMenuId</b></a> 
  can be used for this purpose.&nbsp; Resetting the ids can be useful if you want 
  to prevent inheriting menus that were contributed to superclass menus.&nbsp; 
  For example, the <b>JavaTextEditor</b> in the example resets its context menu 
  ids to be Java specific in order to prevent inheriting any generic text contributions 
  from other plug-ins. </p>
<pre>protected void initializeEditor() {
	super.initializeEditor();
	JavaEditorEnvironment.connect(this);
	setSourceViewerConfiguration(new JavaSourceViewerConfiguration());
	<b>setEditorContextMenuId(&quot;#JavaEditorContext&quot;); 
	setRulerContextMenuId(&quot;#JavaRulerContext&quot;); </b>
}</pre>
<p>If no id is set anywhere in the 
  concrete hierarchy, the default ids defined by <b><a href="../reference/api/org/eclipse/ui/texteditor/AbstractTextEditor.html">AbstractTextEditor</a></b> 
  will be used. </p>
<h4>1.0 Non-compatible Menu Ids </h4>
<p>The editor context menu id is always <code>&lt;editor id&gt;.EditorContext</code>, 
  where <code>&lt;editor id&gt;</code> is the id of the editor . The id of an 
  editor is defined in the xml declaration of the editor. The ruler context menu 
  id is always <code>&lt;editor id&gt;.RulerContext</code>.</p>


</BODY>
</HTML>
